Crate alloy_json_rpc

Alloy JSON-RPC data types.

This crate provides data types for use with the JSON-RPC 2.0 protocol. It does not provide any functionality for actually sending or receiving JSON-RPC data.

If you find yourself importing this crate, and you are not implementing a JSON-RPC client or transport, you are likely at the wrong layer of abstraction. If you want to use a JSON-RPC client, consider using the alloy-transports crate.

Usage

This crate models the JSON-RPC 2.0 protocol data-types. It is intended to be used to build JSON-RPC clients or servers. Most users will not need to import this crate.

This crate provides the following low-level data types:

• Request - A JSON-RPC request.
• Response - A JSON-RPC response.
• ErrorPayload - A JSON-RPC error response payload, including code and message.
• ResponsePayload - The payload of a JSON-RPC response, either a success payload, or an ErrorPayload.

For client-side Rust ergonomics, we want to map responses to Results. To that end, we provide the following types:

• RpcError - An error that can occur during JSON-RPC communication. This type aggregates errors that are common to all transports, such as (de)serialization, error responses, and includes a generic transport error.
• RpcResult - A result modeling an Rpc outcome as Result<T, RpcError<E>>.

We recommend that transport implementors use RpcResult as the return type for their transport methods, parameterized by their transport error type. This will allow them to return either a successful response or an error.

Note On (De)Serialization

Request, Response, and similar types are generic over the actual data being passed to and from the RPC. We can achieve partial (de)serialization by making them generic over a serde_json::RawValue.

• For Request - PartiallySerializedRequest is a Request<Box<RawValue>. It represents a Request whose parameters have been serialized. SerializedRequest, on the other hand is a request that has been totally serialized. For client-development purposes, its Id and method have been preserved.
• For Response - BorrowedResponse is a Response<&RawValue>. It represents a Response whose Id and return status (success or failure) have been deserialized, but whose payload has not.

Allowing partial serialization lets us include many unlike Request objects in collections (e.g. in a batch request). This is useful for implementing a client.

Allowing partial deserialization lets learn request status, and associate the raw response data with the corresponding client request before doing full deserialization work. This is useful for implementing a client.

In general, partially deserialized responses can be further deserialized. E.g. an BorrowedRpcResult may have success responses deserialized with crate::try_deserialize_ok::<U>, which will transform it to an RpcResult<U>.

Structs

• ErrorPayload
  A JSON-RPC 2.0 error object.
• EthNotification
  An ethereum-style notification, not to be confused with a JSON-RPC notification.
• Request
  A JSON-RPC 2.0 request object.
• RequestMeta
  RequestMeta contains the Id and method name of a request.
• Response
  A JSON-RPC 2.0 response object containing a ResponsePayload.
• SerializedRequest
  A JSON-RPC 2.0 request object that has been serialized, with its Id and method preserved.

Enums

• Id
  A JSON-RPC 2.0 ID object. This may be a number, a string, or null.
• PubSubItem
  An item received over an Ethereum pubsub transport.
• RequestPacket
  A RequestPacket is a SerializedRequest or a batch of serialized request.
• ResponsePacket
  A ResponsePacket is a Response or a batch of responses.
• ResponsePayload
  A JSON-RPC 2.0 response payload.
• RpcError
  An RPC error.
• SubId
  A subscription ID.

Traits

• RpcObject
  An object that can be used as a JSON-RPC parameter and return value.
• RpcParam
  An object that can be used as a JSON-RPC parameter.
• RpcReturn
  An object that can be used as a JSON-RPC return value.

Functions

• transform_response
  Transform a transport response into an RpcResult, discarding the Id.
• transform_result
  Transform a transport outcome into an RpcResult, discarding the Id.
• try_deserialize_ok
  Attempt to deserialize the Ok(_) variant of an RpcResult.

Type Aliases

• BorrowedErrorPayload
  A ErrorPayload that has been partially deserialized, borrowing its contents from the deserializer. This is used primarily for intermediate deserialization. Most users will not require it.
• BorrowedResponse
  A Response that has been partially deserialized, borrowing its contents from the deserializer. This is used primarily for intermediate deserialization. Most users will not require it.
• BorrowedResponsePacket
  A BorrowedResponsePacket is a ResponsePacket that has been partially deserialized, borrowing its contents from the deserializer.
• BorrowedResponsePayload
  A ResponsePayload that has been partially deserialized, borrowing its contents from the deserializer. This is used primarily for intermediate deserialization. Most users will not require it.
• BorrowedRpcResult
  A partially deserialized RpcResult, borrowing from the deserializer.
• PartiallySerializedRequest
  A Request that has been partially serialized.
• RpcResult
  The result of a JSON-RPC request.